| Name | Flag System |
| Description | The flag system is a core feature of Denizen, that allows for persistent data storage linked to objects.
"Persistent" means the data is still around even after a server restart or anything else, and is only removed when you choose for it to be removed. "Linked to objects" means rather than purely global values, flags are associated with a player, or an NPC, or a block, or whatever else. See also the guide page at https://guide.denizenscript.com/guides/basics/flags.html. For non-persistent temporary memory, see instead define. For more generic memory options, see yaml or sql. Flags can be sub-mapped with the '.' character, meaning a flag named 'x.y.z' is actually a flag 'x' as a MapTag with key 'y' as a MapTag with key 'z' as the final flag value. In other words, "<server.flag[a.b.c]>" is equivalent to "<server.flag[a].get[b].get[c]>" Server flags can be set by specifying 'server' as the object, essentially a global flag target, that will store data in the file "plugins/Denizen/server_flags.dat" Most unique object types are flaggable - refer to any given object type's language documentation for details. Most flag sets are handled by flag, however items are primarily flagged via inventory with the 'flag' argument. Any supported object type, including the 'server' base tag, can use the tags FlaggableObject.flag, FlaggableObject.has_flag, FlaggableObject.flag_expiration, FlaggableObject.list_flags. Additionally, flags be searched for with tags like server.online_players_flagged, server.players_flagged, server.spawned_npcs_flagged, server.npcs_flagged, ... Flags can also be required by script event lines, as explained at Script Event Switches. Item flags can also be used as a requirement in take. Note that some internal flags exist, and are prefixed with '__' to avoid conflict with normal user flags. This includes: - '__raw' and '__clear' which are part of a fake-flag system used for forcibly setting raw data to a flaggable object, - '__scripts', '__time', etc. which is where some object-type flags are stored inside of server flags, - '__interact_step' which is used for interact script steps, related to zap, - '__interact_cooldown' which is used for interact script cooldowns, related to cooldown. Flags have an expiration system, which is used by specifying a time at which they should expire (or via a duration which internally calculates the date/time of expiration by adding the duration input to the current date/time). Expirations are then *checked for* in flag tags - meaning, the flag tags will internally compare a stored date/time against the real current date/time, and if the flag's expiration time is in the past, the flag tag will return values equivalent to if the flag doesn't exist. There is no system actively monitoring for flag expirations or applying them. There is no event for expirations occurring, as they don't "occur" per se. In other words, it is correct to say a flag "is expired" or a flag "is not expired", but it is incorrect to say a flag "expires", as it is not an active action (though this wording can be convenient when speaking informally). Expired flags are sometimes 'cleaned up' (meaning, any expired flags get actually removed from internal storage), usually when a flag save file is loaded into the server. As a bonus feature-combo, it is possible to transmit sets of flags exactly in-place and reapply them, this is particular useful for example to synchronize player data across Bungee servers. To do this, you can read raw flag data with the tag FlaggableObject.flag_map and the '__raw' prefix in a flag command. For example: |
| Group | Denizen Scripting Language |
| Source | https://github.com/DenizenScript/Denizen-Core/blob/master/src/main/java/com/denizenscript/denizencore/scripts/commands/core/FlagCommand.java#L34 |